home *** CD-ROM | disk | FTP | other *** search
- /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
- *
- * ***** BEGIN LICENSE BLOCK *****
- * Version: MPL 1.1/GPL 2.0/LGPL 2.1
- *
- * The contents of this file are subject to the Mozilla Public License Version
- * 1.1 (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- * http://www.mozilla.org/MPL/
- *
- * Software distributed under the License is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
- * for the specific language governing rights and limitations under the
- * License.
- *
- * The Original Code is the Mozilla browser.
- *
- * The Initial Developer of the Original Code is
- * Netscape Communications, Inc.
- * Portions created by the Initial Developer are Copyright (C) 1999
- * the Initial Developer. All Rights Reserved.
- *
- * Contributor(s):
- * Daniel Glazman <glazman@netscape.com>
- * Akkana Peck <akkana@netscape.com>
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either of the GNU General Public License Version 2 or later (the "GPL"),
- * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
- *
- * ***** END LICENSE BLOCK ***** */
-
- #include "nsISupports.idl"
- #include "domstubs.idl"
-
- interface nsIURI;
- interface nsIAtom;
- interface nsISelection;
- interface nsISelectionController;
- interface nsIDocumentStateListener;
- interface nsIOutputStream;
- interface nsITransactionManager;
- interface nsITransaction;
- interface nsIEditorObserver;
- interface nsIEditActionListener;
- interface nsIInlineSpellChecker;
-
- %{C++
- class nsIPresShell;
- class nsIContent;
- typedef short EDirection;
- %}
-
-
- [ptr] native nsIPresShellPtr(nsIPresShell);
- [ptr] native nsIContentPtr(nsIContent);
-
- [scriptable, uuid(D4882FFB-E927-408b-96BE-D4391B456FA9)]
-
- interface nsIEditor : nsISupports
- {
- %{C++
- typedef short EDirection;
- %}
- const short eNone = 0;
- const short eNext = 1;
- const short ePrevious = 2;
- const short eNextWord = 3;
- const short ePreviousWord = 4;
- const short eToBeginningOfLine = 5;
- const short eToEndOfLine = 6;
-
- readonly attribute nsISelection selection;
-
- /**
- * Init is to tell the implementation of nsIEditor to begin its services
- * @param aDoc The dom document interface being observed
- * @param aPresShell TEMP: The presentation shell displaying the document.
- * Once events can tell us from what pres shell
- * they originated, this will no longer be
- * necessary, and the editor will no longer be
- * linked to a single pres shell.
- * @param aRoot This is the root of the editable section of this
- * document. If it is null then we get root
- * from document body.
- * @param aSelCon this should be used to get the selection location
- * @param aFlags A bitmask of flags for specifying the behavior
- * of the editor.
- */
- [noscript] void init(in nsIDOMDocument doc, in nsIPresShellPtr shell,
- in nsIContentPtr aRoot,
- in nsISelectionController aSelCon,
- in unsigned long aFlags);
-
- void setAttributeOrEquivalent(in nsIDOMElement element,
- in AString sourceAttrName,
- in AString sourceAttrValue,
- in boolean aSuppressTransaction);
- void removeAttributeOrEquivalent(in nsIDOMElement element,
- in DOMString sourceAttrName,
- in boolean aSuppressTransaction);
-
- /**
- * postCreate should be called after Init, and is the time that the editor
- * tells its documentStateObservers that the document has been created.
- */
- void postCreate();
-
- /**
- * preDestroy is called before the editor goes away, and gives the editor a
- * chance to tell its documentStateObservers that the document is going away.
- */
- void preDestroy();
-
- /** edit flags for this editor. May be set at any time. */
- attribute unsigned long flags;
-
- /**
- * the MimeType of the document
- */
- attribute string contentsMIMEType;
-
- /** Returns true if we have a document that is not marked read-only */
- readonly attribute boolean isDocumentEditable;
-
- /**
- * the DOM Document this editor is associated with, refcounted.
- */
- readonly attribute nsIDOMDocument document;
-
- /** the body element, i.e. the root of the editable document.
- */
- readonly attribute nsIDOMElement rootElement;
-
- /**
- * the selection controller for the current presentation, refcounted.
- */
- readonly attribute nsISelectionController selectionController;
-
-
- /* ------------ Selected content removal -------------- */
-
- /**
- * DeleteSelection removes all nodes in the current selection.
- * @param aDir if eNext, delete to the right (for example, the DEL key)
- * if ePrevious, delete to the left (for example, the BACKSPACE key)
- */
- void deleteSelection(in short action);
-
-
- /* ------------ Document info and file methods -------------- */
-
- /** Returns true if the document has no *meaningful* content */
- readonly attribute boolean documentIsEmpty;
-
- /** Returns true if the document is modifed and needs saving */
- readonly attribute boolean documentModified;
-
- /** Sets the current 'Save' document character set */
- attribute ACString documentCharacterSet;
-
- /** to be used ONLY when we need to override the doc's modification
- * state (such as when it's saved).
- */
- void resetModificationCount();
-
- /** Gets the modification count of the document we are editing.
- * @return the modification count of the document being edited.
- * Zero means unchanged.
- */
- long getModificationCount();
-
- /** called each time we modify the document.
- * Increments the modification count of the document.
- * @param aModCount the number of modifications by which
- * to increase or decrease the count
- */
- void incrementModificationCount(in long aModCount);
-
- /* ------------ Transaction methods -------------- */
-
- /** transactionManager Get the transaction manager the editor is using.
- */
- readonly attribute nsITransactionManager transactionManager;
-
- /** doTransaction() fires a transaction.
- * It is provided here so clients can create their own transactions.
- * If a transaction manager is present, it is used.
- * Otherwise, the transaction is just executed directly.
- *
- * @param aTxn the transaction to execute
- */
- void doTransaction(in nsITransaction txn);
-
-
- /** turn the undo system on or off
- * @param aEnable if PR_TRUE, the undo system is turned on if available
- * if PR_FALSE the undo system is turned off if it
- * was previously on
- * @return if aEnable is PR_TRUE, returns NS_OK if
- * the undo system could be initialized properly
- * if aEnable is PR_FALSE, returns NS_OK.
- */
- void enableUndo(in boolean enable);
-
- /** undo reverses the effects of the last Do operation,
- * if Undo is enabled in the editor.
- * It is provided here so clients need no knowledge of whether
- * the editor has a transaction manager or not.
- * If a transaction manager is present, it is told to undo,
- * and the result of that undo is returned.
- * Otherwise, the Undo request is ignored and an
- * error NS_ERROR_NOT_AVAILABLE is returned.
- *
- */
- void undo(in unsigned long count);
-
- /** returns state information about the undo system.
- * @param aIsEnabled [OUT] PR_TRUE if undo is enabled
- * @param aCanUndo [OUT] PR_TRUE if at least one transaction is
- * currently ready to be undone.
- */
- void canUndo(out boolean isEnabled, out boolean canUndo);
-
- /** redo reverses the effects of the last Undo operation
- * It is provided here so clients need no knowledge of whether
- * the editor has a transaction manager or not.
- * If a transaction manager is present, it is told to redo and the
- * result of the previously undone transaction is reapplied to the document.
- * If no transaction is available for Redo, or if the document
- * has no transaction manager, the Redo request is ignored and an
- * error NS_ERROR_NOT_AVAILABLE is returned.
- *
- */
- void redo(in unsigned long count);
-
- /** returns state information about the redo system.
- * @param aIsEnabled [OUT] PR_TRUE if redo is enabled
- * @param aCanRedo [OUT] PR_TRUE if at least one transaction is
- currently ready to be redone.
- */
- void canRedo(out boolean isEnabled, out boolean canRedo);
-
- /** beginTransaction is a signal from the caller to the editor that
- * the caller will execute multiple updates to the content tree
- * that should be treated as a single logical operation,
- * in the most efficient way possible.<br>
- * All transactions executed between a call to beginTransaction and
- * endTransaction will be undoable as an atomic action.<br>
- * endTransaction must be called after beginTransaction.<br>
- * Calls to beginTransaction can be nested, as long as endTransaction
- * is called once per beginUpdate.
- */
- void beginTransaction();
-
- /** endTransaction is a signal to the editor that the caller is
- * finished updating the content model.<br>
- * beginUpdate must be called before endTransaction is called.<br>
- * Calls to beginTransaction can be nested, as long as endTransaction
- * is called once per beginTransaction.
- */
- void endTransaction();
-
- void beginPlaceHolderTransaction(in nsIAtom name);
- void endPlaceHolderTransaction();
- boolean shouldTxnSetSelection();
-
- /** Set the flag that prevents insertElementTxn from changing the selection
- * @param should Set false to suppress changing the selection;
- * i.e., before using InsertElement() to insert
- * under <head> element
- * WARNING: You must be very careful to reset back to PR_TRUE after
- * setting PR_FALSE, else selection/caret is trashed
- * for further editing.
- */
- void setShouldTxnSetSelection(in boolean should);
-
- /* ------------ Inline Spell Checking methods -------------- */
-
- readonly attribute nsIInlineSpellChecker inlineSpellChecker;
-
- /* ------------ Clipboard methods -------------- */
-
- /** cut the currently selected text, putting it into the OS clipboard
- * What if no text is selected?
- * What about mixed selections?
- * What are the clipboard formats?
- */
- void cut();
-
- /** Can we cut? True if the doc is modifiable, and we have a non-
- * collapsed selection.
- */
- boolean canCut();
-
- /** copy the currently selected text, putting it into the OS clipboard
- * What if no text is selected?
- * What about mixed selections?
- * What are the clipboard formats?
- */
- void copy();
-
- /** Can we copy? True if we have a non-collapsed selection.
- */
- boolean canCopy();
-
- /** paste the text in the OS clipboard at the cursor position, replacing
- * the selected text (if any)
- */
- void paste(in long aSelectionType);
-
- /** Can we paste? True if the doc is modifiable, and we have
- * pasteable data in the clipboard.
- */
- boolean canPaste(in long aSelectionType);
-
- /* ------------ Selection methods -------------- */
-
- /** sets the document selection to the entire contents of the document */
- void selectAll();
-
- /** sets the document selection to the beginning of the document */
- void beginningOfDocument();
-
- /** sets the document selection to the end of the document */
- void endOfDocument();
-
- /* ------------ Drag/Drop methods -------------- */
-
- /**
- * canDrag decides if a drag should be started
- * (for example, based on the current selection and mousepoint).
- */
- boolean canDrag(in nsIDOMEvent aEvent);
-
- /**
- * doDrag transfers the relevant data (as appropriate)
- * to a transferable so it can later be dropped.
- */
- void doDrag(in nsIDOMEvent aEvent);
-
- /**
- * insertFromDrop looks for a dragsession and inserts the
- * relevant data in response to a drop.
- */
- void insertFromDrop(in nsIDOMEvent aEvent);
-
- /* ------------ Node manipulation methods -------------- */
-
- /**
- * setAttribute() sets the attribute of aElement.
- * No checking is done to see if aAttribute is a legal attribute of the node,
- * or if aValue is a legal value of aAttribute.
- *
- * @param aElement the content element to operate on
- * @param aAttribute the string representation of the attribute to set
- * @param aValue the value to set aAttribute to
- */
- void setAttribute(in nsIDOMElement aElement, in AString attributestr,
- in AString attvalue);
-
- /**
- * getAttributeValue() retrieves the attribute's value for aElement.
- *
- * @param aElement the content element to operate on
- * @param aAttribute the string representation of the attribute to get
- * @param aResultValue [OUT] the value of aAttribute.
- * Only valid if aResultIsSet is PR_TRUE
- * @return PR_TRUE if aAttribute is set on the current node,
- * PR_FALSE if it is not.
- */
- boolean getAttributeValue(in nsIDOMElement aElement,
- in AString attributestr,
- out AString resultValue);
-
- /**
- * removeAttribute() deletes aAttribute from the attribute list of aElement.
- * If aAttribute is not an attribute of aElement, nothing is done.
- *
- * @param aElement the content element to operate on
- * @param aAttribute the string representation of the attribute to get
- */
- void removeAttribute(in nsIDOMElement aElement,
- in AString aAttribute);
-
- /**
- * cloneAttribute() copies the attribute from the source node to
- * the destination node and delete those not in the source.
- *
- * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
- * @param aAttribute the name of the attribute to copy
- * @param aDestNode the destination element to operate on
- * @param aSourceNode the source element to copy attributes from
- * @exception NS_ERROR_NULL_POINTER at least one of the nodes is null
- * @exception NS_ERROR_NO_INTERFACE at least one of the nodes is not an
- * element
- */
- void cloneAttribute(in AString aAttribute,
- in nsIDOMNode aDestNode, in nsIDOMNode aSourceNode);
-
- /**
- * cloneAttributes() is similar to nsIDOMNode::cloneNode(),
- * it assures the attribute nodes of the destination are identical
- * with the source node by copying all existing attributes from the
- * source and deleting those not in the source.
- * This is used when the destination node (element) already exists
- *
- * The supplied nodes MUST BE ELEMENTS (most callers are working with nodes)
- * @param aDestNode the destination element to operate on
- * @param aSourceNode the source element to copy attributes from
- */
- void cloneAttributes(in nsIDOMNode destNode, in nsIDOMNode sourceNode);
-
- /**
- * createNode instantiates a new element of type aTag and inserts it
- * into aParent at aPosition.
- * @param aTag The type of object to create
- * @param aParent The node to insert the new object into
- * @param aPosition The place in aParent to insert the new node
- * @return The node created. Caller must release aNewNode.
- */
- nsIDOMNode createNode(in AString tag,
- in nsIDOMNode parent,
- in long position);
-
- /**
- * insertNode inserts aNode into aParent at aPosition.
- * No checking is done to verify the legality of the insertion.
- * That is the responsibility of the caller.
- * @param aNode The DOM Node to insert.
- * @param aParent The node to insert the new object into
- * @param aPosition The place in aParent to insert the new node
- * 0=first child, 1=second child, etc.
- * any number > number of current children = last child
- */
- void insertNode(in nsIDOMNode node,
- in nsIDOMNode parent,
- in long aPosition);
-
-
- /**
- * splitNode() creates a new node identical to an existing node,
- * and split the contents between the two nodes
- * @param aExistingRightNode the node to split.
- * It will become the new node's next sibling.
- * @param aOffset the offset of aExistingRightNode's
- * content|children to do the split at
- * @param aNewLeftNode [OUT] the new node resulting from the split,
- * becomes aExistingRightNode's previous sibling.
- */
- void splitNode(in nsIDOMNode existingRightNode,
- in long offset,
- out nsIDOMNode newLeftNode);
-
- /**
- * joinNodes() takes 2 nodes and merge their content|children.
- * @param aLeftNode The left node. It will be deleted.
- * @param aRightNode The right node. It will remain after the join.
- * @param aParent The parent of aExistingRightNode
- *
- * There is no requirement that the two nodes be
- * of the same type. However, a text node can be
- * merged only with another text node.
- */
- void joinNodes(in nsIDOMNode leftNode,
- in nsIDOMNode rightNode,
- in nsIDOMNode parent);
-
- /**
- * deleteNode removes aChild from aParent.
- * @param aChild The node to delete
- */
- void deleteNode(in nsIDOMNode child);
-
- /**
- * markNodeDirty() sets a special dirty attribute on the node.
- * Usually this will be called immediately after creating a new node.
- * @param aNode The node for which to insert formatting.
- */
- void markNodeDirty(in nsIDOMNode node);
-
- /* ---------- direction controller ---------- */
-
- /**
- * Switches the editor element direction; from "Left-to-Right" to
- * "Right-to-Left", and vice versa.
- */
- void switchTextDirection();
-
- /* ------------ Output methods -------------- */
-
- /**
- * Output methods:
- * aFormatType is a mime type, like text/plain.
- */
- AString outputToString(in AString formatType,
- in unsigned long flags);
- void outputToStream(in nsIOutputStream aStream,
- in AString formatType,
- in ACString charsetOverride,
- in unsigned long flags);
-
-
- /* ------------ Various listeners methods -------------- */
-
- /** add an EditorObserver to the editors list of observers. */
- void addEditorObserver(in nsIEditorObserver observer);
-
- /** Remove an EditorObserver from the editor's list of observers. */
- void removeEditorObserver(in nsIEditorObserver observer);
-
- /** add an EditActionListener to the editors list of listeners. */
- void addEditActionListener(in nsIEditActionListener listener);
-
- /** Remove an EditActionListener from the editor's list of listeners. */
- void removeEditActionListener(in nsIEditActionListener listener);
-
- /** Add a DocumentStateListener to the editors list of doc state listeners. */
- void addDocumentStateListener(in nsIDocumentStateListener listener);
-
- /** Remove a DocumentStateListener to the editors list of doc state listeners. */
- void removeDocumentStateListener(in nsIDocumentStateListener listener);
-
-
- /* ------------ Debug methods -------------- */
-
- /**
- * And a debug method -- show us what the tree looks like right now
- */
- void dumpContentTree();
-
- /** Dumps a text representation of the content tree to standard out */
- void debugDumpContent() ;
-
- /* Run unit tests. Noop in optimized builds */
- void debugUnitTests(out long outNumTests, out long outNumTestsFailed);
- };
-